ObiWan is dedicated to beta testers and freeware and shareware authors.
• Contents
What ObiWan Does
Features
Using ObiWan
Using Master Yoda
Database Format
How It Works
Limitations
Small Print
Warranty
Fine Print
Version History
Acknowledgements
The Author
• What ObiWan Does
ObiWan is a general help system. You can create several databses and ObiWan will let you rapidly find information from them. It displays the information by temporarily taking over several lines at the bottom of the main screen, so the information can be displayed at any time in any program. Portions of the information can then be sent to the front window as if you had typed it. The main use of all this is to access the programming database created from Apple’s PInterfacesHelp file, which includes the procedures, traps, global variables and errors available up to System 7.
• Features
The Force file includes all the System 7 information.
The Force database is created from the PInterfacesHelp file for easy updating.
Any number of databases may exist, only one of which is active at any time.
The hot keys may be changed at will via the control panel.
First word searches are instantaneous, general searches are very quick.
Databases are plain text files and can be edited at any time they are not active.
Databases are reindexed automatically when the file size changes.
Database file size is unlimited.
Databases can have any number of entries.
There is absolutely no dependency on MacTCP at all.
Caveats:
Clicks occasionally go thru to the area of the screen that ObiWan has taken over, causing an unwanted application switch. Whether I can fix this is an open question. Anyone from Apple care to comment why sometimes jGNEFilter isn’t called?
The Finder seems to notice the loss of screen real estate, and moves the icons from underneath the area. It only does this if the icon is within four pixels (I believe) of the edge, so placing the icons a little further away will normally fix this problem.
Keys typed in to ObiWan also go into a DA window if a DA is front-most.
• Using Master Yoda
Launch Master Yoda.
If you prefer C over Pascal, click Set Insert Proc and select the C Parse Procedure from the Parse Procedures folder. This affects the way command-shift-enter behaves when it insets a procedure into a document.
To parse the PInterfacesHelp file, click the “Parse PInterfacesHelp” button and select the PInterfacesHelp file (don’t select the CInterfacesHelp file, it won’t work), then select a destination for the Force file (the ObiWan Folder is a good place for it), and Master Yoda will create the file (about 720k, but you’ll need about 2Meg of free space to hold some temporary files). This process will take some time, it takes around 3 minutes on a Quadra 700 from RAM disk, or around 10 minutes on a IIsi from HD, or around 45 minutes on a Plus. Move the Force file to the “ObiWan Folder”, and move the “ObiWan Folder” to the Preferences Folder in the System Folder. Then you are all set.
Master Yoda also lets you do other database operations - Select a database, and then click buttons to sort, merge another (sorted) database, get stats on it, etc.
• Using ObiWan
Drop ObiWan into the Control Panels folder (in System 7), or the System Folder (in System 6). Open the control panel and play around with the controls. Move the ObiWan Folder into the Preferences folder (create the Preferences folder if necessary under System 6). The ObiWan Folder contains all of the database files. Restart your Mac. If all goes well, the ObiWan icon will be displayed during the startup sequence.
Here is an example session:
Press command-` (the command key is the cloverleaf key). A small display should open at the bottom of the screen. Type in “a<return>” and a short help will be displayed. Press cmd-. to move forward thru the file, and cmd-, to move backwards. Close and reopen the display by hitting cmd-` twice, and then type in “help<return>”. Double click on ADSP and you will be taken to the secion listing for ADSP. Double click “attnBufSize”. Click at the end of this paragraph, and then press command-shift-enter (enter, not return). Option-click in ObiWan’s display area to return to the ADSP section. Close and reopen ObiWan and type “hparamblockshift-return>”. Press cmd-. to find the next occurence.
The Force database is produced by parsing the PInterfacesHelp file which I have license from Apple. Thanks to Rick Fleischman, Barbara Napier, and Apple Computer, Inc. for waiving the fee to allow the Force file to be distributed. The Force file contains all the System 6 and 7 procedures, constants, errors, and global variables. You can find these by opening ObiWan (cmd-`), typing in the start of the name (eg HOpen) and pressing return. You can then insert the routine into THINK Pascal or C or MPW by pressing cmd-shift-enter. Note that there is a Pascal bias in this database because I am biased towards Pascal, but there is no reason some bright spark couldn’t produce a C equivalent database. You can also look up traps, errors, globals by searching for:
trapA000 - four digit hex number, starting with A
err-108 - decimal number, starting with a minus for OSErrs
err25 - decimal number, positive for system errors.
global910 - three digit hex number for global variables. (QuickDraw globals are not included)
The Force database is not special in any way (except that it contains the programming information for System 7). You can create other databases and switch between them by typing <name><option-return>. Other databases that are available will likely include: a dictionary, a thesaurus (both based on Roget's thesaurus from the Gutenburg project), and possibly a unix database (similar to Force, but for unix commands).
• Database Format
An ObiWan database is just a TEXT file with a strict format, plus some resources in the resource fork. These include the index (which is recalculated if the file size changes); the word character set; and the parse procedure. The format of the text file is (by example):
=|
indexword data
general stuff, up to 10 lines, each up to 80 characters, ending with a|
nextindexword more data
more stuff|
verynextindexedword more and more data
finally ending with|
=|
The file should be sorted by the indexword (Master Yoda’s sort sorts by the entire entry so if you want related parts to stay in the same order when the database is sorted, they must be ordered in that way). The sort order is straight ASCII, case insensitive. Yes, I can hear you screaming “No, no, use the language independent sort order that the system defines”, (and yes, I do think that comma should go outside the quote mark irrespective of what the English teachers would have you believe :-) but I wish to be able to distribute a database file that works on all machines without having to be resorted.
Let’s see if I can define a BNF for the database format:
character ::= chr(9) | chr(32)..chr(126) | chr(128)..chr(255)
lines MUST be at most 80 characters, and should fit onto a Classic screen in Chicago 12 (which means they should be around 60 characters long).
entries MUST be at most 10 lines.
There is no limit to the file size or number of entries (well, ok, the file size is limited by the file system, but thats not my fault, and the number of entries is obviously limited by the size of the file...)
Note: The file absolutely must start and end with =|<cr>. No trailing blank lines.
• How It Works
At startup time ObiWan grabs a bunch of resource from the ObiWan and ObiWan Preferences files, and locks them all away in the system heap. Then it adds itself to the jGNEFilter list, shows its icon, and plays the startup sound. If this process fails then the failed icon is displayed.
Later on, it watches keypresses and if a match for the popup key appears it opens the display at the bottom of the main screen by mucking about with the GreyRegion (a region comprising the combined area of all the screens, minus the little rounded corners on the outermost screen). It then displays the icon and accepts key strokes. When you hit return it takes the first four letters of the word (padding with zeros), and scans thru an index to find where in the database that word comes, then it positions itself in the database and scans the entries until it finds a matching one and displays that. The “anywhere” search is done using Boyer-Moore search routine - this is one of the most elegant and simple routines I’ve ever seen, if you ever do any searching code, check this out, it is hardly any more complicated than a brute force search, but takes time *inversely* proportional to the length of the seach string!
Entering characters into the front application is done by simply returning key down events in response to null events. In v4.0.1 I added support for key codes as well, though Word still gets confused, but thats to be expected.
• Limitations
ObiWan & Master Yoda require System 6 or later and probably require the 128k ROM (or later).
There is a problem with clicks in ObiWan’s display area sometimes going through to a background application, thereby causing the foreground application to be switched out and a background application (commonly the Finder) to be switched in. This happens because the click is sometimes stolen before it gets to the jGNEFilter. I have no idea why this would happen, nor why it happens only sometimes. If anyone has any ideas, please let me know.
There is also a problem that key presses go into DA windows instead of ObiWan. I don’t really think this is a major problem, but perhaps others disagree.
• Small Print
This program is totally free. That’s right, pay nothing now, pay nothing later (but don’t expect me to send you a steak knife or any jewellery :-). If you like it and use it you can show your appreciation by:
Sending me some Email or a Poastcard.
Donating Blood.
Giving me a free trip to wherever you are, or anywhere else.
Picking up some litter.
Or anything else you feel like doing :-)
• Warranty
There is absolutely NO warranty, guarantee, hint, suggestion or anything else that would lead anyone to think that ObiWan or Master Yoda do anything stated in this documentation. It usually does not destroy data (systems, hardware, etc), and has sometimes worked on my Mac IIsi with System 7.0. It should work with system 6, but probably not with systems before then and probably not with the 64k ROM. It might work with the other models, but I don't have them all, so I don't know. It does not require MacTCP in any way shape or form but should work even if you have MacTCP installed :). If it works on your system (or especially if it doesn’t!), send me a postcard or some Email and let me know!
• Fine Print
Peter Lewis hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Peter Lewis will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis or an agent of his has been advised of the possibility of such damages. In no event shall Peter Lewis be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.
APPLE COMPUTER, INC. ("APPLE") MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING MPW. APPLE DOES NOT WARRANT, GUARANTEE OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF MPW IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF MPW IS ASSUMED BY YOU. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.
IN NO EVENT WILL APPLE, ITS DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS BE LIABLE FOR CONSEQUENCTIAL, INCIDENTAL OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY TO USE MPW EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITIES FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. Apple's liabilities to you for actual damages for any cause whatsoever, and regardless of the form of the action (whether in contract, tort (including negligence), product liability or otherwise), will be limited to $50.
And that goes double for Peter Lewis.
• Version History
Still to do -
Yoda:
Finish up Master Yoda
Handle out of disk space errors better
Revamp Yoda’s UI
Master Yoda progress bar needs status display "Parsing" "Sorting" etc.
Temporary files should be placed in the Temporary Items folder
Crashes on LC/6.0.7 when you choose Select Parse Proc.
Mike Engber <engber@newton.apple.com>:
App for viewing the database
Font selection (esp a monospaced font)
Way to specify two or more keywords for one entry
Way to escape | characters
Way to more than 10 lines per entry
Better debugging in Master Yoda (display anomolies)
Other:
Search all databases, basically pretend that there is only a single database as much as possible.
Decent documentation (any volunteers?)
Double click STR# for Prefs and Parse Proc files.
No way to paste in entire struct/record description
Typing in the ObiWan window when a DA is up puts keys into both!
Does not [always?] properly alert user if it can't find the database?
Clicks sometimes go thru to the background app.
Add the appropriate string resource into the ObiWan Preferences and
Pascal Template Procedure so that when you launch them they put up nice
messages saying 'ObiWan Preferences file must be placed in the Obiwan
Folder within your Preferences Folder' and so on.
STR -16397 I think
4.0.1
~Support key codes so it works with terminal apps - still doesn’t work with Word :-)
~Include the Force database
~Report errors a bit better
~Fix MasterYoda parse proc crash
4.0.0d5
~Balloon Help everywhere - THANKS QUINN!
~Added C Parse Procedure
~Improved param block parsing
4.0.0d4
~Sound play only once every N minutes...
~Select the destination of the output Force file
~Add param blocks to database.
~Sounds should play asynchronously.
4.0.0d2
~Fix the cmd-enter bug where it chooses the first word instead of the selected word
~Click in the R2D2 icon to turn typing on.
~No way to set the Switch Database hotkey
• Acknowledgements
Thanks to Jager, Quinn, and Rhys for their ideas and suggestions for ObiWan in the initial design phase. Thanks you J&Q for the initial parsing of the PInterfacesHelp file. Thanks also to the UCC, Curtin, Todd (have fun at RA!), Steve, c.s.m.p, plaza, ftp.apple.com, Stephen, and anyone who uses ObiWan! Special thanks go to those brave souls who risked life and Mac beta testing an unknown program.
FetchNews 1.0.0b - Fetch News for use with NewsWatcher’s demo mode.
MacTCP Watcher 1.1.0 - Display MacTCP’s state information.
Bolo Finder 1.0.2 - Display the results from Mike Ellis' Bolo Tracker.
Bolo RandomMap 1.1.0 - Generate a random map for Bolo.
You can get the latest development versions from redback.cs.uwa.edu.au, but please use the major archives for released version if at all possible. Redback is a long long way from most people, and using it wastes bandwidth on the Australian-US satelite link which is overly congested already. So use the versions posted to the archives (like sumex-aim.stanford.edu or mac.archive.umich.edu), and only use the development versions if you have some specific problem - in which case tell me!)
Send postcards, comments, bug reports, wishes, and payments to:
